<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<title>Theming</title>
<meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 5.1.2 Build 015" />
<meta name="date" content="2011-11-03T11:27:24Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="Theming" />
<meta name="relnum" content="Release 1.5" />
<meta name="partnum" content="E23376-02" />
<link rel="copyright" href="./dcommon/html/cpyr.htm" title="Copyright" type="text/html" />
<link rel="stylesheet" href="./dcommon/css/blafdoc.css" title="Oracle BLAFDoc" type="text/css" />
<link rel="contents" href="toc.htm" title="Contents" type="text/html" />
<link rel="index" href="index.htm" title="Index" type="text/html" />
<link rel="prev" href="style.htm" title="Previous" type="text/html" />
<link rel="next" href="resources.htm" title="Next" type="text/html" />
</head>
<body>
<div class="header"><a id="top" name="top"></a>
<div class="zz-skip-header"><a href="#BEGIN">Skip Headers</a></div>
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td align="left" valign="top"><b>Lightweight UI Toolkit Developer's Guide</b><br />
<b>Release 1.5</b><br />
E23376-02</td>
<td valign="bottom" align="right">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="225">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="./dcommon/gifs/toc.gif" alt="Go To Table Of Contents" /><br />
<span class="icon">Contents</span></a></td>
<td align="center" valign="top"><a href="index.htm"><img src="./dcommon/gifs/index.gif" alt="Go To Index" /><br />
<span class="icon">Index</span></a></td>
</tr>
</table>
</td>
</tr>
</table>
<hr />
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100">
<tr>
<td align="center"><a href="style.htm"><img src="./dcommon/gifs/leftnav.gif" alt="Previous" /><br />
<span class="icon">Previous</span></a>&nbsp;</td>
<td align="center"><a href="resources.htm"><img src="./dcommon/gifs/rightnav.gif" alt="Next" /><br />
<span class="icon">Next</span></a></td>
<td>&nbsp;</td>
</tr>
</table>
<a name="BEGIN" id="BEGIN"></a></div>
<!-- class="header" -->
<div class="ind"><!-- End Header --><a id="BADBCIEI" name="BADBCIEI"></a>
<h1 class="chapter"><span class="secnum">8</span> Theming</h1>
<p>The Lightweight UI Toolkit library supports <a id="sthref163" name="sthref163"></a>pluggable themes similar to CSS and somewhat simpler than Swing's pluggable Look And Feel.</p>
<a id="Z400088c1290505" name="Z400088c1290505"></a>
<div class="sect1">
<h2 class="sect1">Basic Theming</h2>
<p>Every LWUIT component has a style associated with it (see <a href="style.htm#BADGGABB">Chapter 7</a>). This style can be manipulated manually and can be customized using a set of definitions for a specific component type. For example, in order to make the backgrounds for all the buttons red you can use the following theme:</p>
<p><code>Button.bgColor=ff0000</code></p>
<p>This theme sets the background in the style object within the button object to red. A theme can be packaged into a resource file (see <a href="resources.htm#CJBCGCDD">Chapter 9</a>) and it can be loaded or switched in runtime. In order to update a theme after switching you must refresh the root component (the Form/Dialog containing our component tree) using the <code>refreshTheme</code> method to update all styles.</p>
<div align="center">
<div class="inftblnote"><br />
<table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
<tbody>
<tr>
<td align="left">
<p class="notep1">Note:</p>
Manually modified style elements are not updated when switching a theme.</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
<p>For example, if you have a button whose background is customized to blue, and you load or refresh a theme with a different background color for buttons, the new theme affects all button instances except for the one you have modified manually.</p>
<p>This allows you to determine styles for specific components yet still be able to use themes for the general look of the application without worrying about how they affect your changes.</p>
<p>A <a id="sthref164" name="sthref164"></a>theme file is very similar in spirit to CSS, yet it is much simpler and it is structured like a Java properties file. A theme file is comprised of key value pairs. The key acts in a similar way to a CSS selector that indicates the component or attribute affected by the theme value. For example:</p>
<ul>
<li>
<p><code>Button.font</code> &ndash; font for all buttons</p>
</li>
<li>
<p><code>font</code> &ndash; default application font applied to all components where no default is defined</p>
</li>
</ul>
<p>The key element is comprised of an optional unique identifier ID for the component (the <a id="sthref165" name="sthref165"></a>UIID) and a required attribute type. Unlike CSS, themes do not support elements such as hierarchy or more complex selectors.</p>
<p>Component UIIDs correspond to the component class name by convention. For example.: <code>Button</code>, <code>Label</code>, <code>CheckBox</code>, <code>RadioButton</code>, <code>Form</code>, etcetera.</p>
<p>The supported <a id="sthref166" name="sthref166"></a>attributes and their value syntax are illustrated in <a href="#Z4000f6d1290012">Table 8-1</a>:</p>
<div class="tblhruleformal"><a id="sthref167" name="sthref167"></a><a id="Z4000f6d1290012" name="Z4000f6d1290012"></a>
<p class="titleintable">Table 8-1 Attributes&nbsp;</p>
<table class="HRuleFormal" title="Attributes " summary="Add Summary attribute value here." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
<col width="24%" />
<col width="*" />
<thead>
<tr align="left" valign="top">
<th align="left" valign="bottom" id="r1c1-t3">Attribute</th>
<th align="left" valign="bottom" id="r1c2-t3">Value</th>
</tr>
</thead>
<tbody>
<tr align="left" valign="top">
<td align="left" id="r2c1-t3" headers="r1c1-t3">
<p><a id="sthref168" name="sthref168"></a>bgGradient</p>
</td>
<td align="left" headers="r2c1-t3 r1c2-t3">
<p>Determines the values for the gradient of the image. Accepts source/destination color as well as X/Y of the center of a radial gradient.</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r3c1-t3" headers="r1c1-t3">
<p><a id="sthref169" name="sthref169"></a><code>bgColor</code></p>
</td>
<td align="left" headers="r3c1-t3 r1c2-t3">
<p>Hexadecimal number representing the background color for the component in an unselected widget. For example, blue would be: <code>ff</code></p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r4c1-t3" headers="r1c1-t3">
<p><a id="sthref170" name="sthref170"></a>bgImage</p>
</td>
<td align="left" headers="r4c1-t3 r1c2-t3">
<p>Name of an image from within the resource that should be used as the background for this component. The image referenced must exist within the resource using the same name mentioned here. See the resources chapter for further details about resources and theme files.</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r5c1-t3" headers="r1c1-t3">
<p><a id="sthref171" name="sthref171"></a>bgType</p>
</td>
<td align="left" headers="r5c1-t3 r1c2-t3">
<p>Allows determining the type of the background whether it is an image, color, or gradient. Valid values are:</p>
<p>BACKGROUND_IMAGE_SCALED</p>
<p>BACKGROUND_IMAGE_TILE_BOTH</p>
<p>BACKGROUND_IMAGE_TILE_VERTICAL_ALIGN_LEFT</p>
<p>BACKGROUND_IMAGE_TILE_VERTICAL_ALIGN_CENTER</p>
<p>BACKGROUND_IMAGE_TILE_VERTICAL_ALIGN_RIGHT</p>
<p>BACKGROUND_IMAGE_TILE_HORIZONTAL_ALIGN_TOP</p>
<p>BACKGROUND_IMAGE_TILE_HORIZONTAL_ALIGN_CENTER</p>
<p>BACKGROUND_IMAGE_TILE_HORIZONTAL_ALIGN_BOTTOM</p>
<p>BACKGROUND_IMAGE_ALIGNED_TOP</p>
<p>BACKGROUND_IMAGE_ALIGNED_BOTTOM</p>
<p>BACKGROUND_IMAGE_ALIGNED_LEFT</p>
<p>BACKGROUND_IMAGE_ALIGNED_RIGHT</p>
<p>BACKGROUND_IMAGE_ALIGNED_TOP_LEFT</p>
<p>BACKGROUND_IMAGE_ALIGNED_TOP_RIGHT</p>
<p>BACKGROUND_IMAGE_ALIGNED_BOTTOM_LEFT</p>
<p>BACKGROUND_IMAGE_ALIGNED_BOTTOM_RIGHT</p>
<p>BACKGROUND_IMAGE_ALIGNED_CENTER</p>
<p>BACKGROUND_GRADIENT_LINEAR_HORIZONTAL</p>
<p>BACKGROUND_GRADIENT_LINEAR_VERTICAL</p>
<p>BACKGROUND_GRADIENT_RADIAL</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r6c1-t3" headers="r1c1-t3">
<p><a id="sthref172" name="sthref172"></a><code>fgColor</code></p>
</td>
<td align="left" headers="r6c1-t3 r1c2-t3">
<p>Hexadecimal number representing the foreground color for the component usually used to draw the font in an unselected widget. For example, red would be: <code>ff0000</code></p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r7c1-t3" headers="r1c1-t3">
<p><code>font</code></p>
</td>
<td align="left" headers="r7c1-t3 r1c2-t3">
<p>The name of the bitmap or system font from the build XML file.</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r8c1-t3" headers="r1c1-t3">
<p><a id="sthref173" name="sthref173"></a><code>margin</code></p>
</td>
<td align="left" headers="r8c1-t3 r1c2-t3">
<p>The amount of margin for the component defined as 4 comma-separated integer values representing top, bottom, left, and right. For example, <code>1, 2, 3, 4</code> results in 1 pixel margin top, 2 pixels margin bottom, 3 pixels margin left and 4 pixels margin right.</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r9c1-t3" headers="r1c1-t3">
<p><a id="sthref174" name="sthref174"></a><code>padding</code></p>
</td>
<td align="left" headers="r9c1-t3 r1c2-t3">
<p>Padding is identical to margin in terms of format but it updates the padding property of the component. To understand padding versus margin further please refer to the box model explanation in <a href="style.htm#BADIFJEI">Margin and Padding</a>.</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r10c1-t3" headers="r1c1-t3">
<p><a id="sthref175" name="sthref175"></a><code>transparency</code></p>
</td>
<td align="left" headers="r10c1-t3 r1c2-t3">
<p>A number between 0 and 255 representing the opacity of a component's background. 0 means the background of the component doesn't draw at all (fully transparent) while 255 represents a completely opaque background. Notice that this value currently has no effect on background images (although this behavior might change in a future release).</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="tblhruleformal" -->
<p>To install a theme you must load it from the Resources class (see <a href="resources.htm#CJBCGCDD">Chapter 9</a>), from which you receive the already parsed hashtable containing the selectors (keys) and their appropriate values. You then submit this class to the UI manager's <code>setThemeProps</code> method in order to update the current theme. It is a good practice to call <code>refreshTheme</code> on all components in memory (even those that are not visible) otherwise behavior is unpredictable.</p>
</div>
<!-- class="sect1" -->
<a id="Z400088c1290550" name="Z400088c1290550"></a>
<div class="sect1">
<h2 class="sect1">Look and Feel</h2>
<p>While a theme is remarkably powerful and relatively simple, it doesn't allow the deep type of customization some applications require. Developers would often like the ability to control the drawing of all widgets from a single location, relieving them of the need to subclass widgets and manipulate their paint behavior.</p>
<p>LWUIT delegates all drawing to a single abstract base class called <a id="sthref176" name="sthref176"></a><code>LookAndFeel</code>, an instance of which may be obtained from the <code>UIManager</code>. This class has a concrete subclass which provides the default LWUIT look called <code>DefaultLookAndFeel</code>. Both <code>LookAndFeel</code> and <code>DefaultLookAndFeel</code> may be subclassed in order to extend/replace their functionality.</p>
<p>The <a id="sthref177" name="sthref177"></a>look and feel class has methods for determining the boundaries (preferred size) of component types and for painting all components. In addition it has some special methods that allow you to bind special logic to components and manually draw widgets such as scroll bars. It is the responsibility of the Look and Feel developer to properly use the Style objects delivered by the theme. If you replace the look and feel class, you must make sure to extract values appropriately from component styles of the theming functionality or LWUIT can break.</p>
<p>For further details about the look and feel classes, please consult the API documentation.</p>
</div>
<!-- class="sect1" --></div>
<!-- class="ind" -->
<!-- Start Footer -->
<div class="footer">
<hr />
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<col width="33%" />
<col width="*" />
<col width="33%" />
<tr>
<td valign="bottom">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100">
<col width="*" />
<col width="48%" />
<col width="48%" />
<tr>
<td>&nbsp;</td>
<td align="center"><a href="style.htm"><img src="./dcommon/gifs/leftnav.gif" alt="Previous" /><br />
<span class="icon">Previous</span></a>&nbsp;</td>
<td align="center"><a href="resources.htm"><img src="./dcommon/gifs/rightnav.gif" alt="Next" /><br />
<span class="icon">Next</span></a></td>
</tr>
</table>
</td>
<td class="copyrightlogo"><img class="copyrightlogo" src="./dcommon/gifs/oracle.gif" alt="Oracle Logo" /><br />
<span class="copyrightlogo">Copyright&nbsp;&copy;&nbsp;2008, 2011,&nbsp;Oracle&nbsp;and/or&nbsp;its&nbsp;affiliates.&nbsp;All&nbsp;rights&nbsp;reserved.</span> <a href="./dcommon/html/cpyr.htm"><br />
<span class="copyrightlogo">Legal Notices</span></a></td>
<td valign="bottom" align="right">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="225">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="./dcommon/gifs/toc.gif" alt="Go To Table Of Contents" /><br />
<span class="icon">Contents</span></a></td>
<td align="center" valign="top"><a href="index.htm"><img src="./dcommon/gifs/index.gif" alt="Go To Index" /><br />
<span class="icon">Index</span></a></td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<!-- class="footer" -->
</body>
</html>
